Control Data
This chapter discusses control data.
Topics include:
It is usual to leave CUBE Analyst control parameters to their default values, with the user only setting the parameters associated with data input and output file definition. These are described in Standard user control parameters.
Of the remaining parameters, there is a set which is sometimes changed (Secondary user control parameters) and another which is rarely changed (Tuning control).
Most of the parameters in this last set are connected to the operation of CUBE Analyst’s optimization process, and hence are only of interest when there is evidence of poor performance in achieving convergence.
Topics in this section include:
Standard user control parameters
TABLES
Type = Integer(4)
Default = 101, 102, 0, 0
Example: TABLES=101,102,103,104
The input matrix numbers to be used. They are respectively the prior trip matrix and confidence levels, and the cost matrix and confidence levels.
MATID
Type = Character(60)
Default = Blank
Example: Estimated Matrix for Study Area
Matrix identifier. Up to 60 alphanumeric characters can be used to describe the contents of the output matrix. The identifier should be enclosed in single quotes (').
WIDEND
Type = Integer
Default = 2 if hierarchic numbering, 0 otherwise
Range = 0-3
Example: WIDEND = 0
Indicates the format of the Screenline File:
0 = CUBE Analyst establishes the format automatically. For this to happen, all numeric entries in the file need to be right justified for CUBE Analyst to determine the file format unambiguously.
1 = Version six format. This supports the record format where both link flow and link toll data are stored in the same record type.
2 = Version seven format. Two types of screenline record format can be defined at version seven; link flow records (S in column one) or link toll records (T in column one). The former type must be used for CUBE Analyst runs.
3 = Version seven format with a CNode column inserted to support the input of turning counts in addition to link counts.
If hierarchic numbering is in use (HIERND = T), WIDEND must be set to 2 to use the version seven format
MFORM
Type = Integer
Default = 0
Range = 0-4
Example: MFORM = 0
Indicates the format of the output matrix:
0 = Save the matrix in the same format as the input matrix. This is the default action.
1 = TRIPS
2 = TP+/VOYAGER
3 = TRANPLAN
4 = MINUTP
DEC
Type = Character (1)
Default = Blank
Range = '0' to '9', 'S', 'D', or blank
Example: DEC='4'
Defines the precision with which to store values in the output matrix:
Blank = Uses same precision as in the input trip matrix. If just a cost matrix is input, a value of 2 is used.
'0' to '9' = Store numbers in the matrix as integers representing values to the specified number of decimal places.
'S' or 'D' = Store numbers as floating point numbers in either single or double precision. Double precision gives more accuracy to a greater number of decimal places than single. These values give the best representation in the output matrix, but will generally produce a bigger output file. This option is only available if the output matrix format is TP+/VOYAGER.
PSETS
Type = Integer(50)
Default = 1
Range = 1 to Number of paths sets in the input VOYAGER path file
Example = 1,3
Applies only when a VOYAGER path file is input. It defines the path sets to apply when building the intercepts for the screenlines. At least one set must be specified, and sets are referenced by their number rather than by their name.
PVOLS
Type = Integer(50)
Default = 1
Range = 0 to number of volumes in the input VOYAGER path file
Example = 1,2
Applies only when a VOYAGER path file is input. It defines the volumes to apply when building the intercepts for the screenline. If a value of 0 is specified, the volumes will be ignored, and the weighting of alternative routes will be solely defined by the iteration factors. Otherwise, PVOLS is a list of numbers that are 1 or more, representing the selected volume.
NETID
Type = Character(40)
Default = Blank
Example: NETID='Network with estimated link flows'
Network identifier. Up to 40 alphanumeric characters can be used to describe the contents of the output network. The identifier should be enclosed in single quotes ('). NETID is only used if reading part trip data (PRTTRP=T).
EFLOW
Type = Integer
Default = 2
Range = 1-20
Example: EFLOW = 4
The number of the volume field in the output network into which the total link flows estimated by CUBE Analyst will be written. EFLOW is only used if PRTTRP=T.
ELINEn
Type = Integer
Default = ELINE(n)=2+n*2
PT Only
Range = 1-20
Example: ELINE1 = 6
ELINE(n) is the number of the volume field in the output network into which the link flows estimated by CUBE Analyst will be written for line group n. ELINEn is only used if PRTTRP=T and doing a Public Transport matrix estimation.
NFLOW
Type = Character(4)
Default = 'EFLW'
Example: NFLOW = 'EFLW'
Volume field identifier. Up to four alphanumeric characters can be used to indicate the contents of the volume field specified by EFLOW. The identifier should be enclosed in single quotes ('). EFLOW is only used if reading part trip data (PRTTRP=T).
NLINE
Type = Character(4)*8
Default = 'NLINEn='ELGn'
PT Only
Example: NLINE1 = 'ELG1'
Volume field identifier. Up to four alphanumeric characters can be used to indicate the contents of the volume field specified by ELINEn. The identifier should be enclosed in single quotes ('). NLINEn is only used if PRTTRP=T and doing a Public Transport matrix estimation.
ZCONF
Type = Integer
Default = 100
Range = 1-10000
Example: ZCONF =200
Confidence level for side constraints applied to local matrices and derived from estimated district matrix.
Secondary user control parameters
The parameters described in this section would only be used to try to reduce the processing times required to achieve convergence. Refer to Computation times.
MXITER
Type = Integer
Default = 3000
Range = 1-999999
Example: MXITER = 1500
The maximum number of iterations. CUBE Analyst will stop if this number of iterations has been reached and no convergence has been achieved. The model parameter and gradient search files are written out and can be used to restart CUBE Analyst (from the position it was in when it stopped) and the optimization continued. The currently estimated matrix is also output.
ITERH
Type = Integer
Default = Generated by CUBE Analyst
Range = 1-9999
Example: ITERH = 4000
The number of iterations between recalculations of the estimated Hessian matrix.
UTOL
Type = Real
Default = 0.0001
Range = 0.0-99.0
Example: UTOL = 0.05
The accuracy tolerance in detecting convergence or failure. When the maximum absolute size of the search vector is less than this value then the procedure will be deemed to have converged.
IREP
Type = Integer
Default = 3
Range = 1-3
Example: IREP = 2
Reporting level for the optimization log file. See Information in the optimization log file.
IHTYPE
Type = Integer
Default = 4
Range = 0-4
Example: IHTYPE = 2
This controls the type of optimization process used by CUBE Analyst, as shown in the following table. The difference for values 1 - 4 correspond to differences in the way the initial Hessian matrix, H0, is calculated.
Methods of optimization
Tuning control
The parameters documented in this section would normally be changed only in response to an error message generated by CUBE Analyst. In the event of this occurring, please contact generalsupport@Bentley.com for advice.
MXCALL
Type = Integer
Default = 5000
Range = 1-999999
Example: MXCALL = 10000
The maximum number of function evaluations. (This should be greater than MXITER. At least one function evaluation is required at each iteration, possibly more.)
MXFREE
Type= Integer
Default= 4
Range= 1-10
Example: MXFREE = 7
The number of times a parameter may be freed from its bounds.
UMAX
Type = Real
Default = 1.0
Range = 0.0-1000.0
Example: UMAX = 0.5
The maximum allowed search step. If the maximum absolute value of the search vector (called UNORMX in the log report) is greater than this then the entire search vector is multiplied by a term UMAX/UNORMX so that the new maximum entry is equal to UMAX.
Note: Options TRIPM and COSTM work in conjunction with one another.
TRIPM
Type = Logical
Default = True
If TRIPM = T then the input matrix file will contain at least two tables. The first will be the prior trip matrix; the second will be the associated confidence levels.
IF COSTM = F then these will be the only two matrices present in the file.
TRIPM = F is only allowed if COSTM = T.
COSTM
Type = Logical
Default = False
If COSTM = T and TRIPM = T, then the input matrix file will contain four two tables. The first two are as described above; the third will be the cost matrix and the fourth will be the associated confidence levels.
If COSTM = T and TRIPM = F, then the cost and confidence level matrices will be the first and second supplied in the file.
SCRFIL
Type = Logical
Default = True
If SCRFIL = T then an input screenline file is supplied. See Screenline file.
TRPEND
Type = Logical
Default = True
If TRPEND = T then an input trip end data file is supplied. See Trip end file.
INTCPT
Type= Logical
Default= False
If INTCPT=T then an input Intercept file is supplied. See Intercept file.
MODPAR
Type= Logical
Default= False
If MODPAR = T then an input model parameter file is supplied. See Model parameter file.
WARMST
Type= Logical
Default= False
If WARMST = T then gradient search, model parameter, and intercept files are supplied to warm start the estimation calculation. The input of these files from a previous run of the same model should assist the speed of optimization, but see Approaches to running CUBE Analyst.
HIERND
Type= Logical
Default= Set automatically from RCP input file; False if no RCP file input.
HIERND=T indicates that a hierarchic node numbering system is in use. This option only needs to be set if no RCP file is input. If there is an RCP input file, the setting of HIERND in the control file will be ignored.
NODLAB
Type= Logical
Default= False
If NODLAB=T, zone labels will be included in the CUBE Analyst reports. A coordinate file must be supplied containing node labels. Coordinate file.
LNGLAB
Type= Logical
Default= False
LNGLAB=T to include long zone labels in the CUBE Analyst reports. Note that NODLAB = T must also be set to use long labels. If NODLAB=T and LNGLAB=F, the short zone labels will be used. A coordinate file must be supplied containing node labels. See Coordinate file.
PRTTRP
Type= Logical
Default= False
If PRTTRP = T then an input network file is supplied which contains part-trip link flows.
DSTRCT
Type= Logical
Default= False
If DSTRCT = T then a local matrix control file and district definition file must be supplied. See Local matrix control file and District definition file.